przn 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b33677433cd4802ee75ef9d7eb821d2dbb6faf8b1d2364d535b6aa28bffa6eb3
-  data.tar.gz: 930ecad39096eea771759134cd6c7e4a83c55a00ae98c59ead5afea1dcc46f17
+  metadata.gz: 926f4301117fde5642b907fbf96340d1e547af78086eb1fd47ed45fa16472e5e
+  data.tar.gz: 8cbbf68f1d784b6c6ed2ce7ba600c0a214dc8a688a785b5044701b9e8c587b39
 SHA512:
-  metadata.gz: 08eafdea3c2f55a29ccfd879b3bfa1541576be74fbb042cc33c527e39289e3dcf1375a10df033820e37f69e9f6726f580cd19ae468d633d73c9d65a23736674b
-  data.tar.gz: fcbf194e2a090de86a823fd8a0076977db73cf69f857cea6f4406f9fe31c2f44dab60120d61dbda7f10545e2fd750089df8e34233f0808fefd096bcec3cc25e1
+  metadata.gz: 6f6a58582c7a21ccfab9750ee0ebc39525626af2233d503497e933a1d5b108bcf08b34c156115730c145e3c4dd7473b8d48633597d68b487bcc5702e29132183
+  data.tar.gz: 0a3bf226c4c4e6300d515cf50274c1ad266556c9a984df6090ed9dec1dbcc7cc3e878675131e2d26f0e71b1167046f1d5ea3e7f1b0f965101f942e5a728d9967

data/README.md

@@ -23,6 +23,23 @@ przn your_slides.md @42
 
 Out-of-range numbers are clamped to the last slide, so `@9999` jumps to the end.
 
+### Extended-display presenter mode
+
+```
+przn --present your_slides.md
+```
+
+On a setup with a secondary display (projector / external monitor) and running inside [Echoes](https://github.com/amatsuda/echoes), `--present` auto-spawns an **audience window** on the second display showing the clean current slide, while the laptop pane becomes the **presenter view**:
+
+- Current slide rendered as normal
+- Speaker notes (`{::note}` / `<note>` markup) shown in a side strip — stripped from the audience view
+- Next slide's title hint
+- Elapsed-time clock (or, when `rabbit:` is themed, the runner-bar visualization)
+
+If only one display is attached or Echoes isn't the host terminal, `--present` falls back to today's mirror mode with a one-line warning on stderr.
+
+Implementation: the two `przn` processes coordinate over a Unix socket. The presenter forwards every slide navigation as a `goto` message; the audience renders and otherwise stays silent. Notes are not transmitted to the audience side.
+
 ### PDF export
 
 Two flavors:
@@ -58,6 +75,8 @@ przn --export prawn -o output.pdf your_slides.md
 
 przn's Markdown format is compatible with [Rabbit](https://rabbit-shocker.org/)'s Markdown mode.
 
+> **HTML-ish tag attributes** — every `<tag attr=value>` block below (`<bg>`, `<at>`, `<img>`, `<font>`) accepts three value forms: double-quoted `attr="value"`, single-quoted `attr='value'`, and unquoted `attr=value` (HTML5-ish — anything that isn't whitespace, `=`, `<`, `>`, a quote, or backtick). Self-closing tags need a space before `/>` when the last attribute is unquoted (`<img src=foo.png />`).
+
 ### Slide splitting
 
 Slides are separated by `#` (h1) headings.
@@ -218,6 +237,49 @@ content...
 
 The previous slide's background is cleared on every navigation, and on `przn` exit, so your shell isn't left tinted.
 
+### Absolute-position text
+
+Place text at an arbitrary `(column, row)` on the slide, escaping the normal top-down paragraph flow:
+
+```markdown
+# Layout test
+
+<at x="10" y="5">top-left ish</at>
+<at x="40" y="15"><size=3>BIG</size></at>
+<at x="80" y="25"><color=red>warn</color></at>
+<at x="50%" y="50%">dead center</at>
+
+{::at x="10" y="20"}same thing, kramdown form{:/at}
+```
+
+- `x` / `y` accept two forms:
+  - **Plain integer** — 1-based terminal cells, matching the cursor-position escape (`\e[y;xH`). `x="1" y="1"` is the very top-left of the slide pane.
+  - **Percent** (`x="50%"`, `y="100%"`) — resolves against the terminal's current width / height. Auto-adjusts when the pane is resized.
+- Content is parsed inline, so all the usual styling works inside an `<at>` — `<size>`, `<color>`, `<font>`, `**bold**`, `*italic*`, etc.
+- The block doesn't take up vertical space in the slide's layout — paragraphs around it render in their normal positions and the absolute placement layers on top. Useful for overlaying labels on a `<bg .../>` gradient or pinning annotations to specific cells.
+- Out-of-range coordinates clamp into the visible area; missing / unparseable coordinates skip silently.
+
+### Image
+
+Embed an image with the standard markdown form, or the `<img>` XML form when you want to absolute-position it. Both produce identical output — `<img>` just opens the door to extra attributes like `x` / `y`.
+
+```markdown
+![](doge.png){:relative_height="70"}
+<img src="doge.png" relative_height="70"/>
+
+<img src="doge.png" x="5"   y="3"   relative_height="40"/>
+<img src="doge.png" x="50%" y="50%" relative_height="40"/>
+```
+
+- `src` is required; `alt` and `title` are accepted and ignored at render time (kept for accessibility / future use).
+- `relative_height="N"` caps the image at N % of the terminal height (default 70). Aspect ratio is preserved. `relative_width="N"` is the same for the horizontal dimension.
+- `height="N%"` / `width="N%"` are short-form aliases for `relative_height` / `relative_width` (both forms — `<img>` and `![]{:...}` — accept the alias). An explicit `relative_*` on the same block wins; a non-`%` value (`height="40"`) is left alone since pixel units aren't supported.
+- `x` / `y` (optional) anchor the image's top-left at an absolute cell. Same two forms as [`<at>`](#absolute-position-text):
+  - **Plain integer** — 1-based terminal cells.
+  - **Percent** — resolves against the terminal's current width / height.
+  - With `x` and `y` set, the image layers on top of the slide and contributes 0 to the layout flow — paragraphs around it render in their normal positions, exactly like `<at>`. Without `x` / `y`, the image stays horizontally centered and takes up its natural height in the flow.
+- Rendering backend: Kitty Graphics Protocol on terminals that support it (PNG uploaded once and reused; JPG goes through `kitten icat`), Sixel as a fallback. Other terminals show nothing in place of the image.
+
 ### Comments
 
 ```markdown
@@ -285,6 +347,9 @@ background:               # default slide background (Echoes OSC 7772)
   to:                     # gradient endpoint
   angle:                  # gradient angle in degrees
 
+# rabbit:                 # opt into the 🐇 / 🐢 bottom progress indicator
+#   duration: "30m"       # "1h30m", "1800s", or plain integer seconds; turtle hides when unset
+
 colors:
   code_bg: "313244"
   dim: "6c7086"
@@ -298,6 +363,7 @@ Notes:
 - **`font.family`** — applied to body text (terminal: via OSC 66 `f=`, requires Echoes; PDF: registered via fontconfig). Inline `<font face="...">` runs override it per-segment.
 - **`title`** — h1 typography. Each attribute is independent from `font`: `title.family` does **not** inherit `font.family`, `title.color` does **not** inherit `font.color`. `title.size` defaults to x-large (OSC 66 `s=4`). When `title.family` is proportional, every h1 OSC 66 sequence is emitted with `h=2` so a terminal that honors centered horizontal alignment ([Echoes](https://github.com/amatsuda/echoes)) keeps the title visually centered against its reserved cell block. h2–h6 stay body text.
 - **`background`** — the deck-wide default background. A per-slide `<bg .../>` directive overrides it for that slide. The Prawn fallback paints the PDF page in `background.color` when set; otherwise it leaves the page Prawn's default (white).
+- **`rabbit`** — opt-in Rabbit-style bottom-row progress indicator. With the key absent, przn shows the simple `N / M` counter at the bottom-right. With the key present, the bottom row becomes: current slide # at the very left, total at the very right, 🐇 running between them tracking slide progress. Set `rabbit.duration` to also show 🐢 tracking elapsed time against the goal; without a duration the turtle stays hidden. Inside [Echoes](https://github.com/amatsuda/echoes) the emojis are emitted via OSC 7772 `;multicell` with `flip=h` so they face rightward; outside Echoes they fall back to standard OSC 66 and render unflipped (left-facing).
 
 ## License
 

data/Rakefile

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
 task default: :test

data/default_theme.yml

@@ -33,3 +33,11 @@ colors:
   code_bg: "313244"
   dim: "6c7086"
   inline_code: "a6e3a1"
+
+# Bottom-of-screen progress indicator (a nod to the Rabbit presentation tool).
+# Without this key, przn shows a simple " N / M " counter at the bottom-right.
+# To opt in: uncomment the block. The 🐇 rabbit anchors slide progress between
+# the left (current) and right (total) numbers. Set `duration:` to enable the
+# 🐢 turtle tracking elapsed time against the goal.
+# rabbit:
+#   duration:           # "30m", "1h30m", "1800s", or plain integer seconds

data/exe/przn

@@ -7,7 +7,7 @@ require 'optparse'
 
 options = {}
 OptionParser.new do |opts|
-  opts.banner = "Usage: przn [options] <presentation.md>"
+  opts.banner = 'Usage: przn [options] <presentation.md>'
   opts.on('--export [FORMAT]', 'Export to a format (pdf | prawn; default: pdf)') { |v|
     if v && v.end_with?('.md')
       ARGV.unshift(v)
@@ -19,12 +19,15 @@ OptionParser.new do |opts|
   opts.on('-o', '--output FILE', 'Output file path for export') { |v| options[:output] = v }
   opts.on('--theme FILE', 'Theme file (YAML)') { |v| options[:theme] = v }
   opts.on('--generate-theme', 'Generate theme.yml in current directory') { options[:generate_theme] = true }
+  opts.on('--present', 'Open the deck in presenter mode (auto-spawns an audience window on the secondary display)') { options[:present] = true }
+  opts.on('--audience', 'Run as the audience receiver (spawned by --present; expects --socket)') { options[:audience] = true }
+  opts.on('--socket PATH', 'Unix socket path used by --present/--audience to coordinate') { |v| options[:socket] = v }
 end.parse!
 
 if options[:generate_theme]
   content = File.read(Przn::Theme::DEFAULT_PATH).sub(/\A(#[^\n]*\n)+\n/, '')
   File.write('theme.yml', content)
-  puts "Generated: theme.yml"
+  puts 'Generated: theme.yml'
   exit
 end
 
@@ -38,7 +41,7 @@ end
 
 file = ARGV[0]
 unless file
-  $stderr.puts "Usage: przn [options] <presentation.md> [@N]"
+  $stderr.puts 'Usage: przn [options] <presentation.md> [@N]'
   exit 1
 end
 
@@ -50,11 +53,25 @@ end
 
 case options[:export]
 when 'pdf'
+  require_relative '../lib/przn/screenshot_pdf_exporter'
+
   output = options[:output] || File.basename(file, File.extname(file)) + '.pdf'
   Przn.export_pdf(file, output, theme: theme)
 when 'prawn'
+  require_relative '../lib/przn/prawn_pdf_exporter'
+
   output = options[:output] || File.basename(file, File.extname(file)) + '.pdf'
   Przn.export_pdf_prawn(file, output, theme: theme)
 else
-  Przn.start(file, theme: theme, start_at: start_at).run
+  if options[:audience]
+    unless options[:socket]
+      $stderr.puts 'przn: --audience requires --socket PATH'
+      exit 1
+    end
+    Przn.audience(file, socket: options[:socket], theme: theme)
+  elsif options[:present]
+    Przn.present(file, theme: theme, theme_path: options[:theme]).run
+  else
+    Przn.start(file, theme: theme, start_at: start_at).run
+  end
 end

data/lib/przn/audience_link.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'socket'
+
+module Przn
+  # Tiny line-delimited JSON protocol over a Unix-domain socket, joining the
+  # presenter and audience `przn` processes in extended-display mode.
+  #
+  # Messages currently exchanged:
+  #   {"type": "ready"}                  audience -> presenter
+  #   {"type": "goto", "index": N}       presenter -> audience
+  #   {"type": "quit"}                   presenter -> audience
+  module AudienceLink
+    module_function
+
+    # Audience-side: open a UNIXServer at `path`, wait for the presenter to
+    # connect, then yield each decoded message until EOF or {"type":"quit"}.
+    # The socket file is unlinked on exit.
+    def serve(path)
+      File.unlink(path) if File.exist?(path)
+      server = UNIXServer.new(path)
+      client = server.accept
+      send(client, {type: "ready"})
+      while (line = client.gets)
+        msg = JSON.parse(line.chomp, symbolize_names: true)
+        break if msg[:type] == "quit"
+        yield msg
+      end
+    rescue Errno::EPIPE, EOFError, IOError
+      # Presenter went away; let the caller exit cleanly.
+    ensure
+      client&.close
+      server&.close
+      File.unlink(path) if path && File.exist?(path)
+    end
+
+    # Presenter-side: connect to an audience socket at `path` and return a
+    # client object that responds to `#send` and `#close`. Caller drives the
+    # protocol from the controller.
+    def connect(path)
+      UNIXSocket.new(path)
+    end
+
+    def send(io, msg)
+      io.puts(JSON.generate(msg))
+    rescue Errno::EPIPE, IOError
+      # Other side hung up — caller decides whether to keep going.
+    end
+  end
+end

data/lib/przn/controller.rb

@@ -2,14 +2,16 @@
 
 module Przn
   class Controller
-    def initialize(presentation, terminal, renderer)
+    def initialize(presentation, terminal, renderer, audience_link: nil)
       @presentation = presentation
       @terminal = terminal
       @renderer = renderer
+      @audience_link = audience_link
       @preload_gen = 0
     end
 
     def run
+      @started_at = Time.now
       @terminal.enter_alt_screen
       @terminal.hide_cursor
       render_current
@@ -37,7 +39,12 @@ module Przn
     ensure
       @preload_gen += 1
       @preload_thread&.join
+      if @audience_link
+        AudienceLink.send(@audience_link, type: "quit")
+        @audience_link.close
+      end
       @terminal.write "\e]7772;bg-clear\a"
+      @terminal.write ImageUtil.kitty_clear_all if ImageUtil.kitty_terminal?
       @terminal.show_cursor
       @terminal.leave_alt_screen
     end
@@ -48,8 +55,15 @@ module Przn
       @renderer.render(
         @presentation.current_slide,
         current: @presentation.current,
-        total: @presentation.total
+        total: @presentation.total,
+        started_at: @started_at
       )
+      if @audience_link
+        AudienceLink.send(@audience_link,
+                          type: "goto",
+                          index: @presentation.current,
+                          started_at: @started_at.to_f)
+      end
       schedule_preload
     end
 

data/lib/przn/echoes_client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require 'json'
+require 'timeout'
+
+module Przn
+  # Thin wrappers around Echoes-specific OSC 7772 commands the presenter uses
+  # to set up extended-display mode. Other terminals ignore OSC 7772, so each
+  # method silently fails (returns nil / false) when not running inside Echoes.
+  module EchoesClient
+    OSC = "\e]7772"
+    BEL = "\a"
+    REPLY_TIMEOUT_S = 0.5
+
+    module_function
+
+    # Ask Echoes how many displays are attached and a tiny descriptor for each.
+    # Returns an Array of Hashes like [{index: 0, w: 1920, h: 1080}, ...] or
+    # nil when no reply arrives within the timeout (non-Echoes terminal, or
+    # an Echoes that doesn't speak this command yet).
+    def display_info(io_in: $stdin, io_out: $stdout)
+      io_out.write("#{OSC};display-info#{BEL}")
+      io_out.flush if io_out.respond_to?(:flush)
+      reply = read_osc_reply(io_in)
+      return nil unless reply
+      JSON.parse(reply, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Open a new Echoes window on the given display, running `argv` (an
+    # Array of strings — argv[0] is the executable). `fullscreen:` is a hint.
+    # Returns true if the request was emitted; nothing in the protocol confirms
+    # success synchronously.
+    def open_window(display:, argv:, fullscreen: true, io_out: $stdout)
+      # `pack('m0')` is strict (no-newline) base64 — same as
+      # Base64.strict_encode64 but without pulling in the base64 stdlib,
+      # which is no longer a default gem in Ruby 3.4+.
+      payload = [JSON.generate(argv)].pack('m0')
+      args = "display=#{display}:program=#{payload}:fullscreen=#{fullscreen ? 'yes' : 'no'}"
+      io_out.write("#{OSC};open-window;#{args}#{BEL}")
+      io_out.flush if io_out.respond_to?(:flush)
+      true
+    end
+
+    # Read an OSC reply up to ST or BEL. Returns the payload string or nil on
+    # timeout. Echoes replies follow the same `\e]7772;...\a` shape it accepts.
+    #
+    # Stdin defaults to canonical (line-buffered) mode in a shell context, so
+    # `getc` would block waiting for a newline that an OSC reply never sends.
+    # Put the input in raw mode for the duration of the read; IO#raw saves and
+    # restores termios automatically.
+    def read_osc_reply(io_in)
+      if io_in.respond_to?(:raw) && io_in.respond_to?(:tty?) && io_in.tty?
+        io_in.raw { read_osc_reply_inner(io_in) }
+      else
+        read_osc_reply_inner(io_in)
+      end
+    end
+
+    def read_osc_reply_inner(io_in)
+      Timeout.timeout(REPLY_TIMEOUT_S) do
+        buf = +""
+        loop do
+          c = io_in.getc
+          return nil if c.nil?
+          break if c == BEL
+          if c == "\e"
+            nxt = io_in.getc
+            break if nxt == "\\"
+            buf << c << nxt
+          else
+            buf << c
+          end
+        end
+        buf.sub(/\A\e?\]?7772;[\w-]+;/, '')
+      end
+    rescue Timeout::Error
+      nil
+    end
+  end
+end

data/lib/przn/image_util.rb

@@ -42,14 +42,14 @@ module Przn
         # GIF
         f.seek(0)
         sig = f.read(6)
-        if sig&.start_with?("GIF8")
+        if sig&.start_with?('GIF8')
           w = f.read(2)&.unpack1('v')
           h = f.read(2)&.unpack1('v')
           return [w, h] if w && h
         end
       end
       nil
-    rescue
+    rescue StandardError
       nil
     end
 
@@ -62,7 +62,9 @@ module Przn
     end
 
     def kitty_terminal?
-      ENV['TERM'] == 'xterm-kitty' || ENV['TERM_PROGRAM'] == 'kitty'
+      ENV['TERM'] == 'xterm-kitty' ||
+        ENV['TERM_PROGRAM'] == 'kitty' ||
+        ENV['TERM_PROGRAM'] == 'Echoes'
     end
 
     PNG_MAGIC = "\x89PNG\r\n\x1a\n".b.freeze
@@ -89,6 +91,16 @@ module Przn
       "\e_Ga=p,i=#{image_id},c=#{cols},r=#{rows},q=2\e\\"
     end
 
+    # Kitty Graphics Protocol: delete every placement and free the
+    # stored image data. Used on quit so previously-rendered images
+    # don't leak through onto the user's restored shell screen
+    # (placements aren't tied to the alt-screen buffer in most
+    # kitty-protocol implementations, so leaving the alt screen
+    # alone isn't enough to hide them). `q=2` suppresses the OK reply.
+    def kitty_clear_all
+      "\e_Ga=d,d=A,q=2\e\\"
+    end
+
     # Sixel via img2sixel
     def sixel_available?
       @sixel_available = system('command -v img2sixel > /dev/null 2>&1') if @sixel_available.nil?

data/lib/przn/kitty_text.rb

@@ -5,19 +5,38 @@ module Przn
     HEADING_SCALES = {
       1 => 4,
       2 => 3,
-      3 => 2,
+      3 => 2
     }.freeze
 
     module_function
 
-    def sized(text, s:, h: nil, v: nil, n: nil, d: nil, f: nil)
+    # Emit sized multicell text. The `s/w/n/d/v/h` params are standard kitty
+    # OSC 66 (portable). The `f=` (font family) and `flip=` params are
+    # Echoes-only extensions — when one of them is set AND we're running
+    # inside Echoes, they ride on the private OSC 7772 ;multicell frame so
+    # that strict kitty terminals never see unknown params on OSC 66.
+    # Otherwise the extensions are silently dropped and we emit plain OSC
+    # 66, which renders without the flip / custom font on any kitty-
+    # compatible terminal (better than emitting an OSC 7772 frame the
+    # terminal would ignore entirely).
+    def sized(text, s:, h: nil, v: nil, n: nil, d: nil, f: nil, flip: nil)
       params = +"s=#{s}"
       params << ":n=#{n}" if n
       params << ":d=#{d}" if d
       params << ":h=#{h}" if h
       params << ":v=#{v}" if v
-      params << ":f=#{f}" if f
-      "\e]66;#{params};#{text}\a"
+
+      if (f || flip) && echoes?
+        params << ":f=#{f}" if f
+        params << ":flip=#{flip}" if flip
+        "\e]7772;multicell;#{params};#{text}\a"
+      else
+        "\e]66;#{params};#{text}\a"
+      end
+    end
+
+    def echoes?
+      ENV['TERM_PROGRAM'] == 'Echoes'
     end
 
     def heading(text, level:)